<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.6" />
<title>The GRR Configuration system</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

pre {
  padding: 0;
  margin: 0;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }


/*
 * xhtml11 specific
 *
 * */

tt {
  font-family: monospace;
  font-size: inherit;
  color: navy;
}

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

.monospaced {
  font-family: monospace;
  font-size: inherit;
  color: navy;
}

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}
@media screen {
  body {
    max-width: 50em; /* approximately 80 characters wide */
    margin-left: 16em;
  }

  #toc {
    position: fixed;
    top: 0;
    left: 0;
    bottom: 0;
    width: 13em;
    padding: 0.5em;
    padding-bottom: 1.5em;
    margin: 0;
    overflow: auto;
    border-right: 3px solid #f8f8f8;
    background-color: white;
  }

  #toc .toclevel1 {
    margin-top: 0.5em;
  }

  #toc .toclevel2 {
    margin-top: 0.25em;
    display: list-item;
    color: #aaaaaa;
  }

  #toctitle {
    margin-top: 0.5em;
  }
}
</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>The GRR Configuration system</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>The GRR configuration system is the main way users can control and customize the
behavior of GRR components. Previous versions of GRR used command line flags to
configure component, however that became unwieldy with a lot of confusing and
often contradictory command line options embedded in various shell scripts. We
decided to replace the configuration system with an ini file based system.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_general_configuration_file_structure">General configuration file structure.</h2>
<div class="sectionbody">
<div class="paragraph"><p>The GRR configuration file is based around the concept of an INI file. The file
is broken up into sections, and configuration parameters specific to each
section are given with that. For example:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>

<span style="font-weight: bold"><span style="color: #000000">[NannyWindows]</span></span>
<span style="color: #009900">service_key </span><span style="color: #990000">=</span> HKEY_LOCAL_MACHINE<span style="color: #990000">\\</span>Software<span style="color: #990000">\\</span>GRR</tt></pre></div></div>
<div class="paragraph"><p>All configuration parameters in GRR referred to by their section name followed
by a dot followed by the parameter name. For example above we have
Client.location and <em>NannyWindows.service_key</em> defined.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_parameter_typing">Parameter Typing</h2>
<div class="sectionbody">
<div class="paragraph"><p>When software is written with the GRR configuration system, it can define
parameters that it is going to use. This declares the sections, the parameter name
and a helpful message. In addition, the parameter&#8217;s type is also declared. For
example we can find the following code:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>config_lib<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">DEFINE_float</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Client.rss_max"</span><span style="color: #990000">,</span> <span style="color: #993399">500</span><span style="color: #990000">,</span>
                        <span style="color: #FF0000">"Maximum memory footprint in MB."</span><span style="color: #990000">)</span>

config_lib<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">DEFINE_option</span></span><span style="color: #990000">(</span>type_info<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">PEMPrivateKey</span></span><span style="color: #990000">(</span>
    name<span style="color: #990000">=</span><span style="color: #FF0000">"Client.private_key"</span><span style="color: #990000">,</span>
    description<span style="color: #990000">=</span><span style="color: #FF0000">"Client private key in pem format. If not provided this "</span>
    <span style="color: #FF0000">"will be generated by the enrollment process."</span><span style="color: #990000">,</span>
    <span style="color: #990000">))</span></tt></pre></div></div>
<div class="paragraph"><p>The first definition declares the parameter Client.rss_max to be a float, with a
default value of 500.</p></div>
<div class="paragraph"><p>The second definition is more complex. It defines the Client.private_key
parameter as a PEMPrivateKey type info declaration. This declaration allows the
configuration system itself to verify that the parameter is a valid private key
in PEM format. There is now no need for the code to specifically test for sanity
of the private key. If the user provides an invalid or corrupt PEM encoded key,
it is caught immediately by the config system and the program aborts. For
example the following happens after removing a random character from the
CA.certificate PEM string:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>Traceback (most recent call last):
  File "grr/client/client.py", line 48, in &lt;module&gt;
    conf.StartMain(main)
  File "grr/client/conf.py", line 93, in StartMain
    main([sys.argv[0]])
......
  File "grr/lib/config_lib.py", line 467, in _VerifyParameters
    descriptor.Validate(value)
  File "grr/lib/rdfvalues/crypto.py", line 173, in Validate
    return self.ParseFromString(value)
  File "grr/lib/rdfvalues/crypto.py", line 185, in ParseFromString
    raise type_info.TypeValueError("Certificate %s is invalid." % self.name)
grr.lib.type_info.TypeValueError: Certificate CA.certificate is invalid.</tt></pre>
</div></div>
<div class="paragraph"><p>Since every parameter is defined in advance and has a default value, the config
file does not need to specify every parameter - only those which should be
changed from the default value. In order to see all declared parameters and
their default values, we can issue the --config_help command line flag. This is
analogous to the --help flag:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>Client.location = http://www.example.com/control
   URL of the controlling server.
* Value = http://localhost:8080/control

Client.max_out_queue = 10240000
   Maximum size of the output queue.
* Value = 10240000</tt></pre>
</div></div>
<div class="paragraph"><p>We can see that Client.location has a default value of
<a href="http://www.example.com/control">http://www.example.com/control</a>, it is used to specify the URL of the controlling
server, and currently (after reading the configuration files), the value is set
to <a href="http://localhost:8080/control">http://localhost:8080/control</a>. We can also see that Client.max_out_queue is
not changed from its default value.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_executable_sections">Executable sections.</h2>
<div class="sectionbody">
<div class="paragraph"><p>GRR contains many different components, each component having its own
configuration parameters. For example, the Client component refers to the client
binary, the Nanny component is used by the Nanny program etc.</p></div>
<div class="paragraph"><p>When a main component program is run, it is desirable to apply specific
configuration for it, which may be different from other main components. For
example, the parameter Logging.path describes the filename for log files to be
written to. When running the client we might want this to be different than when
running the server.</p></div>
<div class="paragraph"><p>We could solve this problem by having multiple configuration files - one for the
client and one for the server. But this can make is hard to manage and
synchronize.</p></div>
<div class="paragraph"><p>In GRR we have executable sections. When a section is executed, it assigns
configuration directives to other sections, thereby updating their
configuration. For example:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>

<span style="font-weight: bold"><span style="color: #000000">[Logging]</span></span>
<span style="color: #009900">path </span><span style="color: #990000">=</span> <span style="color: #990000">/</span>var<span style="color: #990000">/</span>log<span style="color: #990000">/</span>grr<span style="color: #990000">.</span>log                                        <span style="font-style: italic"><span style="color: #9A1900"># <img src="./images/icons/callouts/1.png" alt="1" /></span></span>

<span style="font-weight: bold"><span style="color: #000000">[NannyWindows]</span></span>
<span style="color: #009900">service_key </span><span style="color: #990000">=</span> HKEY_LOCAL_MACHINE<span style="color: #990000">\\</span>Software<span style="color: #990000">\\</span>GRR
<span style="color: #009900">Logging.path </span><span style="color: #990000">=</span> <span style="color: #990000">/</span>var<span style="color: #990000">/</span>log<span style="color: #990000">/</span>grr_nanny<span style="color: #990000">.</span>log                          <span style="font-style: italic"><span style="color: #9A1900"># <img src="./images/icons/callouts/2.png" alt="2" /></span></span></tt></pre></div></div>
<div class="colist arabic"><table>
<tr><td><img src="./images/icons/callouts/1.png" alt="1" /></td><td>
This configuration parameter specifies the name of the log file that is used
normally.
</td></tr>
<tr><td><img src="./images/icons/callouts/2.png" alt="2" /></td><td>
When the nanny main program is run, it executes its section (called
Nanny). This causes this parameter to assign a different value to the
Logging.path parameter. The overall result is that the nanny program will now log
to a different path than everyone else.
</td></tr>
</table></div>
<div class="paragraph"><p>This technique can be used to create a single configuration file, which causes
different behaviors in different components. For example, we can use this to
configure different parameters for different OS versions of the client. For
example the following causes windows clients and Linux clients to talk to
different front ends:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>

<span style="font-weight: bold"><span style="color: #000000">[ClientWindows]</span></span>
<span style="color: #009900">Client.location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>windows<span style="color: #990000">/</span>

<span style="font-weight: bold"><span style="color: #000000">[ClientLinux]</span></span>
<span style="color: #009900">Client.location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>linux<span style="color: #990000">/</span></tt></pre></div></div>
<div class="paragraph"><p>In addition to components executing sections, it is possible to specify that
sections be executed from the command line. This allows the same config file to
specify a number of <em>roles</em>, which are fairly similar except for some small
number of parameters which differ. For example, one might want to test the
client on a test server prior to deployment:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>frontend<span style="color: #990000">/</span>


<span style="font-weight: bold"><span style="color: #000000">[TestClient]</span></span>
<span style="color: #009900">Client.location </span><span style="color: #990000">=</span> http<span style="color: #990000">://</span>www<span style="color: #990000">.</span>example<span style="color: #990000">.</span>com<span style="color: #990000">/</span>test_frontend<span style="color: #990000">/</span></tt></pre></div></div>
<div class="paragraph"><p>Then launching the client will override the Client&#8217;s location temporarily:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>client<span style="color: #990000">.</span>py --config_execute TestClient</tt></pre></div></div>
</div>
</div>
<div class="sect1">
<h2 id="_parameter_expansions">Parameter Expansions</h2>
<div class="sectionbody">
<div class="paragraph"><p>The GRR configuration file format allows for expansion of configuration
parameters inside other parameters. For example consider the following
configuration file:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">name </span><span style="color: #990000">=</span> GRR

<span style="font-weight: bold"><span style="color: #000000">[NannyWindows]</span></span>
<span style="color: #009900">service_name </span><span style="color: #990000">=</span> <span style="color: #990000">%(</span>Client<span style="color: #990000">.</span>name<span style="color: #990000">)</span>service<span style="color: #990000">.</span>exe
<span style="color: #009900">service_key_hive </span><span style="color: #990000">=</span> HKEY_LOCAL_MACHINE
<span style="color: #009900">service_key </span><span style="color: #990000">=</span> Software<span style="color: #990000">\\%(</span>Client<span style="color: #990000">.</span>name<span style="color: #990000">)</span>
<span style="color: #009900">initial_commandline </span><span style="color: #990000">=</span></tt></pre></div></div>
<div class="paragraph"><p>The expansion sequence <em>%(parameter_name)</em> substitutes or expands the parameter
into the string. This allows us to build values automatically based on other
values. For example above, the <em>NannyWindows.service_name</em> will be
<em>GRRservice.exe</em> and the service_key will be set to <em>Software\GRR</em></p></div>
<div class="paragraph"><p>Expansion is very useful, but sometimes it gets in the way. For example, if we
need to pass literal % escape sequences. Consider the Logging.format parameter
which is actually a python format string:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Logging]</span></span>
<span style="color: #009900">format </span><span style="color: #990000">=</span> <span style="color: #990000">\%(</span>levelname<span style="color: #990000">\)</span>s <span style="color: #990000">\%(</span>module<span style="color: #990000">\)</span>s<span style="color: #990000">:\%(</span>lineno<span style="color: #990000">\)</span>s<span style="color: #990000">]</span> <span style="color: #990000">\%(</span>message<span style="color: #990000">\)</span>s  <span style="font-style: italic"><span style="color: #9A1900"># <img src="./images/icons/callouts/1.png" alt="1" /></span></span>
<span style="color: #009900">format </span><span style="color: #990000">=</span> <span style="color: #990000">%</span>{<span style="color: #990000">%(</span>levelname<span style="color: #990000">)</span>s <span style="color: #990000">%(</span>module<span style="color: #990000">)</span>s<span style="color: #990000">:%(</span>lineno<span style="color: #990000">)</span>s<span style="color: #990000">]</span> <span style="color: #990000">%(</span>message<span style="color: #990000">)</span>s}       <span style="font-style: italic"><span style="color: #9A1900"># <img src="./images/icons/callouts/2.png" alt="2" /></span></span></tt></pre></div></div>
<div class="colist arabic"><table>
<tr><td><img src="./images/icons/callouts/1.png" alt="1" /></td><td>
This form escapes GRR&#8217;s special escaping sequence by preceding both opening
and closing sequences with the backslash character.
</td></tr>
<tr><td><img src="./images/icons/callouts/2.png" alt="2" /></td><td>
This variation uses the literal expansion sequence <em>%{}</em> to declare the
entire line as a literal string and prevent expansion.
</td></tr>
</table></div>
</div>
</div>
<div class="sect1">
<h2 id="_filtering">Filtering</h2>
<div class="sectionbody">
<div class="paragraph"><p>The configuration system may be extended to provide additional functionality
accessible from the configuration file. For example consider the following
configuration file:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Logging]</span></span>
<span style="color: #009900">path </span><span style="color: #990000">=</span> <span style="color: #990000">%(</span>HOME<span style="color: #990000">|</span>env<span style="color: #990000">)/</span>grr<span style="color: #990000">.</span>log                             <span style="font-style: italic"><span style="color: #9A1900"># <img src="./images/icons/callouts/1.png" alt="1" /></span></span></tt></pre></div></div>
<div class="colist arabic"><table>
<tr><td><img src="./images/icons/callouts/1.png" alt="1" /></td><td>
This expansion sequence uses the <em>env</em> filter which expands a value from the
environment. In this case the environment variable <em>HOME</em> will be expanded into
the <em>Logging.path</em> parameter to place the log file in the user&#8217;s home directory.
</td></tr>
</table></div>
<div class="paragraph"><p>There are a number of additional interesting filters. The <em>file</em> filter allows
including other files from the filesystem into the configuration file. For
example, some people prefer to keep their certificates in separate files rather
than paste them into the config file:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[CA]</span></span>
<span style="color: #009900">certificate </span><span style="color: #990000">=</span> <span style="color: #990000">%(/</span>etc<span style="color: #990000">/</span>certificates<span style="color: #990000">/</span>ca<span style="color: #990000">.</span>pem<span style="color: #990000">|</span>file<span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>It is even possible to nest expansion sequences. For example this retrieves the
client&#8217;s private key from a location which depends on the client name:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">[Client]</span></span>
<span style="color: #009900">private_key </span><span style="color: #990000">=</span> <span style="color: #990000">%(/</span>etc<span style="color: #990000">/</span>grr<span style="color: #990000">/</span>client<span style="color: #990000">/%(</span>Client<span style="color: #990000">.</span>name<span style="color: #990000">)/</span>private_key<span style="color: #990000">.</span>pem<span style="color: #990000">|</span>file<span style="color: #990000">)</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
<h2 id="_configuration_parsers">Configuration parsers</h2>
<div class="sectionbody">
<div class="paragraph"><p>The above describes the GRR configuration system as an INI file and that is the
most commonly used format. However, configuration files are parsed using a
parser implementation which can be switched on demand. Currently there are a few
configuration parser implementations but additional ones can be added.</p></div>
<div class="paragraph"><p>The windows client implements a registry based configuration parser. This allows
GRR to use the registry instead of a flat file when running on windows. The
registry base parser is selected by using a URL of the form:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.5
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>client<span style="color: #990000">.</span>py --config reg<span style="color: #990000">:</span>//HKEY_LOCAL_MACHINE/Software/GRR</tt></pre></div></div>
<div class="paragraph"><p>In future additional parsers may be implemented.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2013-04-03 16:23:41 CEST
</div>
</div>
</body>
</html>
